Promis.e Help

Project API Builder Overview

The Project API (Application Programming Interface) Builder can be used to automate the building of new projects or for changing existing ones. This tool requires that you have MS-Excel on your computer as the input file is an MS-Excel file with the ending xls.

When activated, the Project API Builder executes a series of functions that are defined in the Excel file. For complex applications, such as the building of attachments that are based on variables, additional software is necessary. This can be made with any development environment that runs on the operating system and can create or edit Excel files. For example, for databases, all that is necessary is an interface that changes the data into the Excel format of the project API builder.

Project API Command File Format

File Format Description
Legacy File Format A legacy format used by the Project-API function of earlier versions of Promis.e. This format can be recognized by a header row in line 1 that consists of COM in column A, PAR1 in column B, PAR2 in column C, and so on. Column A is for comments while subsequent columns contain function codes and parameter values.
Standard File Format Supports some of the newer features of the software such as drawing sets. This format can be recognized by the second line which contains function code SCRIPT in column B with a value of 2 in column C.

As with the legacy format, the first line is a header row that consists of COM in column A, PAR1 in column B, PAR2 in column C, and so on.



Column A is for comments.

Column B holds function codes while subsequent columns contain parameter values related to the function.

Available Functions

The following functions are available for use in the Project API Builder.

API Builder Functions Description
PRJ - Create/Open Project
  • Column B: Contains the function code PRJ.
  • Column C: Contains the name of the project that will be opened or created. If you enter only the project name the software will use the default project folder specified in the Promis.e Setup dialog. You can also enter a complete path for the project if you wish to use a different folder.
  • Column D: contains the name of a project from which the project settings will be taken. It's useful to define a master project with all necessary project parameters and use it here. This eliminates the need to define all the project parameters in the Project API Builder command file. If you leave the field blank, the software will use the default settings for new projects.
  • Column E: This column contains the Workspace name.
  • Column F: This column contains the Workset name.
  • Column G: This column and above can contain project descriptions. You can enter as many descriptions as you wish.
INS - Create/Open Installation
  • Column B: Contains the function code INS.
  • Column C: Installation name.
  • Column D: This column and above contain installation descriptions. You can enter as many as you wish.
PAG - Create/Open Page
  • Column B: Contains the function code PAG.
  • Column C: Drawing set name.
  • Column D: Installation name.
  • Column E: Workspace name.
  • Column F: Workset name.
  • Column G: Location name.
  • Column H: Page number.
  • Column I: Page format.
  • Column J: Page scale (enter 1 for 1:1, enter 2 for 1:2, etc.)
  • Column K: Title block.
  • Column L: Drawing modes.

    Column M: Use or overwrite existing page. Enter 0 to use an existing page. Enter 1 to overwrite and existing page.

  • Column N: Page macro.
  • Column O: Device ID update mode. This setting determines how IDs and wire numbers are updated on macros when they are placed on the page. This setting affects all macros placed on the page unless the MAC function (see below) includes a similar setting, in which case the setting in the MAC function will override the setting in the PAG function for that particular macro. Enter one of the following values (0, 1, 2, 4, 8, 16 or 32):
    • 0 = Maintain Nothing
    • 1 = Maintain Device ID Tag Only
    • 2 = Maintain Wire Number Tag Only
    • 4 = Maintain Wire Link Tag Only
    • 8 = Maintain Device ID Complete
    • 16 = Maintain Wire Number Complete
    • 32 = Maintain Wire Link Complete
  • Column P: Set page online or offline. 0 = Online page; 1 = Offline page.
  • Column Q: This column and higher contain page descriptions. Yo can enter as many as you wish.
MAC - Insert Macro With this function you can insert a macro in a drawing.
  • Column B: Contains the function code MAC.
  • Column C: Macro name.
  • Column D: Macro insertion point x coordinate.
  • Column E: Macro insertion point Y coordinate.
  • Column F: Macro insertion point Z coordinate.
  • Column G: Snap to Grid. 0 = No; 1 = Yes.
  • Column H: Device ID update mode. This setting determines how IDs and wire numbers are updated on macros when they are placed on the page. This setting will override the setting in the PAG function for this particular macro. Enter one of the following values (0, 1, 2, 4, 8, 16 or 32):
    • 0 = Maintain Nothing
    • 1 = Maintain Device ID Tag Only
    • 2 = Maintain Wire Number Tag Only
    • 4 = Maintain Wire Link Tag Only
    • 8 = Maintain Device ID Complete
    • 16 = Maintain Wire Number Complete
    • 32 = Maintain Wire Link Complete
  • Column I: Allow sub-ID. If a device ID is assigned that belongs to a family that is already full, this setting allows the new item to be added to the family as an auxiliary child (sub-ID).
    • 1 = Allow sub-ID.
    • 0 = Do not allow sub-ID (device ID will contain a "?").
TXT - Replace Texts With this function, you can exchange various kinds of texts in a project with new values. You can enter codes to specify the type of texts that are to be replaced. If used after the MAC function, the TXT function will only affect the macro that was placed. You can reset the TXT function so that it affects the entire project by using the SPARE function.

  • Column B: Contains the function character TXT.
  • Column C: #_OldText where # is the selection code that determines which type of text is to be replaced and OldText is the existing text to be replaced. See the section below for an explanation of the selection code.
  • Column D: The new text string that is to replace the old text.
  • Column E: The connection point and device ID replacement method. Enter one of the following values:
    • 0 = Question mark on error.
    • 1 = Try alternate child on error.
    • 2 = Force new sub-ID on error.
  • Column F: Text attribute name. If you wish to limit the replacement to a single text attribute enter the attribute name here.
Selection Code This number, used in the TXT function, defines the categories of text that will be included in the replacement. It consists of a number between 1 and 4095. Examples:
  • 4_F1 means search for device ID F1
  • 2048_X1:100 means search for the terminal block X1:100
You can combine multiple categories into a single code number by adding two or more codes and using that value. Example:
  • 96_Stop means search Symbol text and Free texts for "Stop." (32+64=96)
The following are the individual codes:
  • 1 Installation
  • 2 Location
  • 4 Device ID
  • 8 Part Number
  • 16 Connection Point
  • 32 Symbol Text
  • 64 Free Texts
  • 128 Potential Number
  • 256 Logical Field Texts
  • 512 Title Block Texts
  • 1024 Cable Texts
  • 2048 Terminal Blocks
  • 4095 All information that can be found in the project
SPARE - Reset the TXT function When you use the TXT function following the MAC function, the TXT function will only apply to the last macro that was placed. By putting the SPARE function in the list of functions, the TXT function will be reset so that it applies to the entire project.

SYM - Place Symbol With this function, you can place a symbol in a drawing.

  • Column B: Contains the function code SYM.
  • Column C: Symbol name.
  • Column D: Family name.
  • Column E: Symbol insertion point X coordinate.
  • Column F: Symbol insertion point Y coordinate.
  • Column G: Symbol insertion point Z coordinate.
  • Column H: Symbol scale. Scale values allow the symbol to be reduced (0.5 for half size) or enlarged (2 for double size).
  • Column I: Symbol rotation value.
  • Column J: Mirror symbol:
    • 0 = No mirror
    • 1 = Mirror on X axis
    • 2 = Mirror on Y axis
  • Column K: Auto ID assignment:
    • 0 = Yes - assign device ID automatically using the project's default format.
    • 1 = No
Line - Draw Wire Use this function to draw a wire in a drawing.

  • Column B: contains the function code LINE.
  • Column C: Drawing mode.
  • Column D: Wire X1 coordinate.
  • Column E: Wire Y1 coordinate.
  • Column F: Wire X2 coordinate.
  • Column G: Wire Y2 coordinate.
  • Column H: Wire color (on the drawing page).
  • Column I: Line style.
Project API Builder
Parent topic: Project API Builder